swagger: '2.0'
schemes:
  - https
host: trips.furkot.com
basePath: /pub/api
info:
  contact:
    email: trips@furkot.com
  description: |
    Furkot provides Rest API to access user trip data.
    Using Furkot API an application can list user trips and display stops for a specific trip.
    Furkot API uses OAuth2 protocol to authorize applications to access data on behalf of users.
  title: Furkot Trips
  version: 1.0.0
  x-apisguru-categories:
    - location
  x-logo:
    url: 'https://api.apis.guru/v2/cache/logo/https_cdn.furkot.com_img_furkot-banner-black-4x1.svg'
  x-origin:
    - format: swagger
      url: 'https://help.furkot.com/widgets/furkot-api.yaml'
      version: '2.0'
  x-preferred: true
  x-providerName: furkot.com
externalDocs:
  description: Furkot API description
  url: 'https://help.furkot.com/widgets/furkot-api.html'
produces:
  - application/json
securityDefinitions:
  furkot_auth_access_code:
    authorizationUrl: 'https://trips.furkot.com/oauth/authorize'
    flow: accessCode
    scopes:
      'read:trips': list trips and stops info
    tokenUrl: 'https://trips.furkot.com/pub/api/access_token'
    type: oauth2
  furkot_auth_implicit:
    authorizationUrl: 'https://trips.furkot.com/oauth/authorize'
    flow: implicit
    scopes:
      'read:trips': list users trips info
    type: oauth2
security:
  - furkot_auth_access_code:
      - 'read:trips'
  - furkot_auth_implicit:
      - 'read:trips'
paths:
  /trip:
    get:
      description: list user's trips
      responses:
        '200':
          description: Successful response
          schema:
            items:
              $ref: '#/definitions/Trip'
            type: array
  '/trip/{trip_id}/stop':
    get:
      description: 'list stops for a trip identified by {trip_id}'
      parameters:
        - description: id of the trip
          in: path
          name: trip_id
          required: true
          type: string
      responses:
        '200':
          description: Successful response
          schema:
            items:
              $ref: '#/definitions/Step'
            type: array
definitions:
  Step:
    properties:
      address:
        description: address of the stop
        type: string
      arrival:
        description: 'arrival at the stop in its local timezone as YYYY-MM-DDThh:mm'
        format: date-time
        type: string
      coordinates:
        description: geographical coordinates of the stop
        properties:
          lat:
            description: latitude
            format: float
            type: number
          lon:
            description: longitude
            format: float
            type: number
        type: object
      departure:
        description: 'departure from the stop in its local timezone as YYYY-MM-DDThh:mm'
        format: date-time
        type: string
      name:
        description: name of the stop
        type: string
      nights:
        description: number of nights
        format: int64
        type: integer
      route:
        description: route leading to the stop
        properties:
          distance:
            description: route distance in meters
            format: int64
            type: integer
          duration:
            description: route duration in seconds
            format: int64
            type: integer
          mode:
            description: travel mode
            enum:
              - car
              - motorcycle
              - bicycle
              - walk
              - other
            type: string
          polyline:
            description: route path compatible with Google polyline encoding algorithm
            type: string
        type: object
      url:
        description: url of the page with more information about the stop
        type: string
    type: object
  Trip:
    properties:
      begin:
        description: 'begin of the trip in its local timezone as YYYY-MM-DDThh:mm'
        format: date-time
        type: string
      description:
        description: description of the trip (truncated to 200 characters)
        type: string
      end:
        description: 'end of the trip in its local timezone as YYYY-MM-DDThh:mm'
        format: date-time
        type: string
      id:
        description: Unique ID of the trip
        type: string
      name:
        description: name of the trip
        type: string
    type: object
